﻿"""
    Document   : jamendo_radio_rpc.py
    Package    : Jamendo Radio
    Author     : Ángel Fernández Pineda
    Copyright  : 2011, Ángel Fernández Pineda, Spain
    License    : Gnu General Public License - see LICENSE.TXT
    Description: partial Jamendo RPC API
"""
"""
    This file is part of "Jamendo Radio plugin for XBMC"

    The "Jamendo Radio plugin for XBMC" is free software: you can redistribute
    it and/or modify it under the terms of the GNU General Public License as
    published by the Free Software Foundation, either version 3 of the License,
    or (at your option) any later version.

    The "Jamendo Radio plugin for XBMC" is distributed in the hope that it will
    be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.

    You should have received a copy of the GNU General Public License
    along with the "Jamendo Radio plugin for XBMC".
    If not, see <http://www.gnu.org/licenses/>.
"""
import jamendo_rpc
import random

def get_listener_id():
    """
     Compute a random listener id, required by Jamendo API

     @return string
        A random-generated string
    """
    return str(random.random()).replace('.',"")
#end def

def get_radio_stations():
    """
     Retrieve a list of Jamendo radio stations.

     @return list of dictionaries
        Each dictionary has string values with keys 'id', 'name' and 'image'
    """
    return jamendo_rpc.query(["id","name","image"],"radio",{"n":"all"})
#end def

def get_playlist(radio_id_str, listener_id_str, radio_pos_int):
    """
     Retrieves a small list of streams.

     @param radio_id_str string
         A radio station identifier, retrieved by get_radio_stations().
     @param listener_id_str
         An arbitrary string, use _get_listener_id() to retrieve one
     @param radio_pos_int int
         Position of the first retrieved stream in the global playlist.
         Starts with 0.
     @result list of dictionaries
         Each dictionary has string values with keys
         'id', 'name', 'album_image', 'stream', 'album_name' and 'duration'
     Notes:
         Jamendo API retrieves an arbitrary but small number of
         streams for each call. As a result, it must be called in a loop.
         In order to avoid the same song being repeated, use radio_pos_int
         accordingly
    """
    return jamendo_rpc.query(
        ['id', 'name', 'album_image', 'stream', 'album_name','duration'],
        "track",
        {    "radioposition": radio_pos_int,
             "radiolisteneridstr": listener_id_str,
             "radioid": radio_id_str
        })
#end def
